feat(data-view): lane per sort value in the timeline - #889

Description

Adds a third timeline lane packing mode: one lane per value of the sorted-by field.

// Sorting the "High"/"Medium"/"Low" label alphabetically gives High, Low, Medium,
// so carry a numeric rank and sort on that.
<DataView
  data={tasks}
  fields={fields}
  defaultSort={{ name: 'rank', order: 'asc' }}
  getRowId={t => t.id}>
  <DataView.Timeline
    startField="start"
    endField="end"
    lanePacking="one-per-sort-value"
    renderCard={renderCard}
  />
</DataView>

Rows sharing a value share a lane, packed by date within it; a value only claims a sub-lane where two of its own cards genuinely overlap in time. So a timeline sorted by priority rank reads as a High lane, a Medium lane and a Low lane, and only the priority with concurrent work grows a second row.

The active sort does double duty: it picks the field lanes are built from and orders them. That means one vocabulary rather than a parallel set of lane props, and the Ordering control rebuilds lanes live.

Behaviour details

• Lane field and order both come from tableQuery.sort[0]. No sort in the query → falls back to auto (the root requires defaultSort, so this is a guard, not a mode).
• Rows with no usable value — null, undefined, "", or a non-primitive (which also logs a dev warning) — share one lane, always last, wherever the sort would have placed them.
• Values are keyed by their string form, so 1 and "1" share a lane.
• With group_by active, each section gets its own lane set and context.laneIndex stays section-relative. Grouping by the sorted field is allowed and degenerates cleanly: a section already holds one value, so it renders as one lane plus sub-lanes on overlap.

Also: declared section order

DataViewField.groupOrder?: string[] ranks group sections for every renderer that groups — ['High', 'Medium', 'Low'], which text sorting can't produce. Values it doesn't list follow in first-occurrence order.

⚠️ Behaviour change, no opt-in required: rows with no value now land in the last section instead of wherever their bucket was first seen. groupData previously emitted groupMap.forEach, i.e. insertion order. Anyone grouping a DataView.List (or a timeline) on a nullable field will see that section move, whether or not they declare groupOrder. group-data.test.ts pins both the declared and undeclared paths.

Sections and timeline lanes share only the empty-bucket-last half of the rule (orderBucketKeys): sections rank by groupOrder, lanes by the sort. One field that is both grouped and sorted can therefore order its sections and its lanes differently — that's the contract of one-per-sort-value, and both call sites say so.

New API

Additive apart from the null-section ordering change called out above.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update
• Test (adding missing tests or correcting existing tests)

How Has This Been Tested?

• 41 new tests: order-bucket-keys.test.ts (9) and group-data.test.ts (7) for section ordering, 11 in pack-lanes.test.ts for packLanesBySortValue (bucketing, sub-lane splits, differential against packLanes for a single bucket, plus randomized no-overlap-within-a-lane and lanes-never-span-buckets invariants), 14 in timeline.test.tsx (lane assignment from the sort, direction flip, relaning when the sort field changes, rank-field ordering, dotted accessorKey paths, a sort key matching no field, null and non-primitive values, per-section lanes under group_by, virtualized culling).
• Full package suite green (228 data-view tests, 2677 in the package); no pre-existing test modified.
• Lane values are read via row.getValue(...), so a dotted accessorKey (meta.rank) lanes on the same value TanStack sorted by; a sort key with no matching field warns instead of silently collapsing.
• tsc --noEmit clean on every file this branch touches, in the package and in apps/www (the repo's other pre-existing errors are unchanged).
• Verified live on the docs site: the demo lanes High (2 lanes — one from a real overlap) → Medium (3) → Low (2) under rank asc, no group bands, console clean.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (.mdx files)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works

Screenshots (if appropriate):

Docs → DataView → Timeline → Lane packing carries a live demo (one lane per priority, sorted by rank, Ordering control left visible) alongside a mode-comparison table.

Related Issues

n/a

🤖 Generated with Claude Code